home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / mods / makers / octamedv4_dev.lha / PlayerLibraries / library.doc < prev    next >
Encoding:
Text File  |  1993-08-27  |  11.8 KB  |  384 lines
  1. ***************************************************************************
  2.  
  3. Instructions for using "medplayer.library" and "octaplayer.library"
  4. V2 - V5, by Teijo Kinnunen.
  5.  
  6. © With exception of the PD V1 ALL further versions are Fully Copyrighted,
  7. (allthough V2 as has now been released as FREEWARE the copyright is retained)
  8.  
  9.    Commercial usage of routines etc from V3 4 AND 5 require a licence.
  10.  
  11. Note to Authors:
  12.  
  13. Use of these library functions is heartily encouraged IF you intend using
  14. them within the Public Domain.
  15. If you intend using them within a program written for gain ie: Commercial
  16. or one of the many low charge libraries,(even if you will only be receiving
  17. a SMALL share per sale),then you MUST by law obtain a licence from
  18. RBF Software. The address is given in the ReadMe file.
  19.  
  20. ***************************************************************************
  21.  
  22.  
  23.         medplayer.library
  24.         ~~~~~~~~~~~~~~~~~
  25.  
  26. "medplayer.library" is a shared library, which can be used to load and play
  27. MED/OctaMED 4-channel modules You can call its functions from any language
  28. which supports library calls (C, Assembler, Basic...)
  29.  
  30. First you must install "medplayer.library" to your LIBS: drawer (click
  31. Install_Libraries to do that). You can also load it with ARP's "loadlib"
  32. command.
  33.  
  34. "medplayer.library" supports only 4-channel MED songs!! For OctaMED 5 - 8
  35. channel songs there's "octaplayer.library".
  36.  
  37. There's  a  header  file  'libproto.h'  that  contains  the  prototypes and
  38. #pragmas for use with SAS/Lattice C V5/6.
  39.  
  40. Here's  the  complete  list of the functions in "medplayer.library" (in RKM
  41. autodoc-style):
  42.  
  43. ---------------------------------------------------------------------------
  44. ---------------------------------------------------------------------------
  45.  
  46. GetPlayer
  47.  
  48. NAME
  49.     GetPlayer -- get and initialize the player routine
  50.  
  51. SYNOPSIS
  52.     error = GetPlayer(midi)
  53.     D0                D0
  54.  
  55. FUNCTION
  56.     This routine allocates the audio channels and CIAB timer A/B
  57.     and prepares the interrupt. If "midi" is nonzero, serial
  58.     port is allocated and initialized. You should call this
  59.     routine when your programs starts up.
  60.  
  61. INPUTS
  62.     midi =  0 no midi, 1 set up midi. When you use a song that
  63.         has only Amiga samples, there's no reason to allocate
  64.         the serial port. Then set midi to 0.
  65.  
  66. RESULT
  67.     If everything is OK, GetPlayer() returns zero. If initialization
  68.     failed or somebody else is currently using the library, then
  69.     GetPlayer() returns nonzero value.
  70.     NOTE: Even if GetPlayer() returned an error, you can still call
  71.           the library functions without making harm. They just won't
  72.           work (except LoadModule(), UnLoadModule(), RelocModule()
  73.           and GetCurrentModule(), which always work).
  74.  
  75. SEE ALSO
  76.     FreePlayer
  77.  
  78. ---------------------------------------------------------------------------
  79. ---------------------------------------------------------------------------
  80.  
  81. FreePlayer
  82.  
  83. NAME
  84.     FreePlayer -- free the resources allocated by GetPlayer()
  85.  
  86. SYNOPSIS
  87.     FreePlayer()
  88.  
  89. FUNCTION
  90.     This routine frees all resources allocated by GetPlayer().
  91.     Remember always call this routine before your program
  92.     exits. It doesn't harm to call this if GetPlayer() failed.
  93.     If you don't call this function during exit, audio channels,
  94.     timer etc. will remain allocated until reboot.
  95.  
  96. SEE ALSO
  97.     GetPlayer
  98.  
  99. ---------------------------------------------------------------------------
  100. ---------------------------------------------------------------------------
  101.  
  102. PlayModule
  103.  
  104. NAME
  105.     PlayModule -- play module from the beginning
  106.  
  107. SYNOPSIS
  108.     PlayModule(module)
  109.                A0
  110.  
  111. FUNCTION
  112.     This routine starts to play the module from the beginning.
  113.     The module can be obtained by calling LoadModule() or it can
  114.     be incorporated directly into your program. The module has to
  115.     be relocated before calling PlayModule()!
  116.  
  117. INPUTS
  118.     module = pointer to the module.
  119.  
  120. SEE ALSO
  121.     ContModule, StopPlayer
  122.  
  123. ---------------------------------------------------------------------------
  124. ---------------------------------------------------------------------------
  125.  
  126. ContModule
  127.  
  128. NAME
  129.     ContModule -- continue playing the module from where it stopped
  130.  
  131. SYNOPSIS
  132.     ContModule(module)
  133.                A0
  134.  
  135. FUNCTION
  136.     ContModule() functions just like PlayModule() except if you
  137.     have stopped playing with StopPlayer(), the playing will
  138.     continue where it stopped. When you play the module first
  139.     time, you should use PlayModule().
  140.  
  141. INPUTS
  142.     module = pointer to module.
  143.  
  144. SEE ALSO
  145.     PlayModule, StopPlayer
  146.  
  147. ---------------------------------------------------------------------------
  148. ---------------------------------------------------------------------------
  149.  
  150. StopPlayer
  151.  
  152. NAME
  153.     StopPlayer -- stops playing immediately
  154.  
  155. SYNOPSIS
  156.     StopPlayer()
  157.  
  158. FUNCTION
  159.     Stop.
  160.  
  161. SEE ALSO
  162.     PlayModule, ContModule
  163.  
  164. ---------------------------------------------------------------------------
  165. ---------------------------------------------------------------------------
  166.  
  167. DimOffPlayer
  168.  
  169. NOTE
  170.     This is an obsolete function! It was removed in V2 of the library,
  171.     and it now just does StopPlayer()!
  172.  
  173. ---------------------------------------------------------------------------
  174. ---------------------------------------------------------------------------
  175.  
  176. SetTempo
  177.  
  178. NAME
  179.     SetTempo -- modify the playing speed
  180.  
  181. SYNOPSIS
  182.     SetTempo(tempo)
  183.              D0
  184.  
  185. FUNCTION
  186.     If you want to modify the playback speed, you can call this one.
  187.     This number should be 1 - 240. Note that tempos 1 - 10 are
  188.     recognized as SoundTracker tempos. This function probably has not
  189.     much use.
  190.  
  191. INPUTS
  192.     tempo = new tempo
  193.  
  194. ---------------------------------------------------------------------------
  195. ---------------------------------------------------------------------------
  196.  
  197. LoadModule
  198.  
  199. NAME
  200.     LoadModule -- load a MED module from disk and relocate it
  201.  
  202. SYNOPSIS
  203.     module = LoadModule(name)
  204.     D0                  A0
  205.  
  206. FUNCTION
  207.     When you want to load a module from disk, call this function.
  208.     The function loads only MED modules (MMD0). It doesn't load
  209.     Tracker-modules, MED songs or object files. Only MMD0's
  210.     (MMD0 is the identification word at the beginning of the file).
  211.     Because the module contains many pointers, they must be
  212.     relocated. This function relocates the module automatically.
  213.     If you include the module as a binary file converted with
  214.     Objconv, YOU must relocate it. This is an easy thing to do.
  215.     Just call RelocModule().
  216.  
  217.     Version 3 of medplayer.library also handles OctaMED Pro type
  218.     modules (MMD1).
  219.  
  220. INPUTS
  221.     name = pointer to file name (null-terminated)
  222.  
  223. RESULT
  224.     module = pointer to module. If failed to load for some reason
  225.              (disk error, out of memory, not a module), zero will
  226.           be returned.
  227.  
  228. SEE ALSO
  229.     UnLoadModule
  230.  
  231. ---------------------------------------------------------------------------
  232. ---------------------------------------------------------------------------
  233.  
  234. UnLoadModule
  235.  
  236. NAME
  237.     UnLoadModule -- frees the module from memory
  238.  
  239. SYNOPSIS
  240.     UnLoadModule(module)
  241.                  A0
  242. FUNCTION
  243.     When you don't need the module anymore, you MUST free the
  244.     memory it has used. Use this routine for it. Remember to
  245.     stop the player before unloading the module it is playing.
  246.  
  247.     NOTE: unload only those modules which are loaded with
  248.     LoadModule(). If you attempt to free module which is a part
  249.     of the program, you will cause guru 81000009/81000005.
  250.  
  251. INPUTS
  252.     module = pointer to module. If zero, nothing happens.
  253.  
  254. SEE ALSO
  255.     LoadModule
  256.  
  257. ---------------------------------------------------------------------------
  258. ---------------------------------------------------------------------------
  259.  
  260. GetCurrentModule
  261.  
  262. NAME
  263.     GetCurrentModule -- returns the address of module currently playing
  264.  
  265. SYNOPSIS
  266.     module = GetCurrentModule()
  267.     D0
  268.  
  269. FUNCTION
  270.     Simply returns the pointer of the module, which is currently
  271.     playing (or if player is stopped, which was played last). This
  272.     works also if some other task is currently playing. In this case,
  273.     because of multitasking, you should have no use for the value
  274.     (the module can be already unloaded). You may ask what use this
  275.     function has. Well, I'm not sure, but because this function
  276.     takes only 2 machine language instructions (8 bytes of memory)
  277.     there's not much harm of it.
  278.  
  279. RESULT
  280.     module = pointer to current module
  281.  
  282. ---------------------------------------------------------------------------
  283. ---------------------------------------------------------------------------
  284.  
  285. ResetMIDI
  286.  
  287. NAME
  288.     ResetMIDI -- reset all pitchbenders and modulation wheels and
  289.                  ask player to resend the preset values
  290.  
  291. SYNOPSIS
  292.     ResetMIDI()
  293.  
  294. FUNCTION
  295.     This function resets pitchbenders and modulation wheels on all
  296.     MIDI channels. It also asks the player to send again the
  297.     preset change requests for all instruments, so that the presets
  298.     will be correct if the user has changed them. It performs the
  299.     same function as Ctrl-Space in OctaMED.
  300.  
  301. ---------------------------------------------------------------------------
  302. ---------------------------------------------------------------------------
  303. NOTE: THE FOLLOWING FUNCTIONS ARE ONLY AVAILABLE IN MEDPLAYER.LIBRARY V2
  304. OR LATER, BE SURE THAT YOU'RE REALLY USING V2 OF THE LIBRARY
  305. e.g.  MEDPlayerBase = OpenLibrary("medplayer.library",2);
  306. ---------------------------------------------------------------------------
  307. ---------------------------------------------------------------------------
  308.  
  309. SetModnum
  310.  
  311. NAME
  312.     SetModnum -- select the number of the song (in multi-module)
  313.  
  314. SYNOPSIS
  315.     SetModnum(modnum)
  316.           D0
  317.  
  318. FUNCTION
  319.     Use this function to set the number of song you want to play.
  320.     Call this before PlayModule(). 0 is the first song, 1 is the
  321.     second, and so on. If the module is not a multi-module, this
  322.     function has no effect.
  323.  
  324. ---------------------------------------------------------------------------
  325. ---------------------------------------------------------------------------
  326.  
  327. RelocModule
  328.  
  329. NAME
  330.     RelocModule -- relocate module
  331.  
  332. SYNOPSIS
  333.     RelocModule(module)
  334.             A0
  335.  
  336. FUNCTION
  337.     This function relocates the module. It should be used if you have
  338.     incorporated the module with Objconv program before using the
  339.     module. Note that LoadModule() automatically relocs everything.
  340.  
  341. ---------------------------------------------------------------------------
  342. ***************************************************************************
  343.  
  344.         octaplayer.library
  345.         ~~~~~~~~~~~~~~~~~~
  346.  
  347. This library is made for playing OctaMED 5 - 8 channel songs ONLY. It
  348. doesn't support MIDI or 4-channel songs. The functions in it work quite
  349. similarly as medplayer.library's functions. See the medplayer.library docs
  350. above for explanation of the functions, as the functions in octaplayer.
  351. library work in the same way.
  352.  
  353. The functions are:
  354.  
  355.     GetPlayer8()
  356.     FreePlayer8()
  357.     PlayModule8(module)
  358.     ContModule8(module)
  359.     StopPlayer8()
  360.     LoadModule8(filename)
  361.     UnLoadModule8(module)
  362.     SetModnum8(modnum)
  363.     RelocModule8(module)
  364.  
  365. As you can see, every function has '8' in its name, and some functions that
  366. are in medplayer.library don't exist.
  367.  
  368. ***************************************************************************
  369. Notes:
  370. ~~~~~~
  371. Version 3 of both medplayer.library and octaplayer.library handle the new
  372. MMD1 module type correctly. No changes are required to programs calling
  373. these libraries. If you absolutely want MMD1 support, be sure to request
  374. V3 of the libraries.
  375.  
  376. (e.g. OpenLibrary("medplayer.library",3); )
  377.  
  378. Version 5 (+ later) of the libraries support the MMD2 format of OctaMED
  379. Pro V5. There is no version 4 of the libraries. The version number was
  380. lifted to 5 so that it's parallel with the main OctaMED program.
  381.  
  382. The libraries keep track of the current user by comparing the task
  383. address. Therefore, you should call all routines within a single task.
  384. ***************************************************************************